GitHub Portfolio
Matthew Harris
11/20/2020
A Project Portfolio with GitHub Pages
This markdown is about making a simple project portfolio on GitHub using GitHub pages, Markdown, Jekyll, and Rstudio. Requirements for this are a GitHub account, Git command line tool installed on your computer, Rstudio, and some knowledge of markdown and perhaps HTML. Fortunately, GitHub Pages takes care of converting markdown to HTML pages and serving them to the internet. Aside from some preliminary setup, your work will be about editing an index.md document and committing you project example markdowns to GitHub. We will walk through all of these steps. This walk-throught is adapted from this blog post and uses the same theme as a base.
GitHub
GitHub is a platform for code version control and collaboration. It is also a free service to host code, data, and some web serving capabilities. We are going to use it initially for hosting a project portfolio to showcase your markdowns and code. Beyond this use, learning Git and GitHub is a skill that is very useful for controlling your own code and collaborating with others. Below are some links to help get familiar with what Git and GitHub have to offer.
Jekyll and Markdown
Steps
The steps below cover the entire process for how to create a GitHub portfolio. Steps 1 through 6 only need to be completed once. Steps 7 through 12 are completed in an iterative process will you edit the portfolio and add projects.
- Make github account
- Install git on your computer: see links above or https://git-scm.com/downloads
- Configure git in Rstudio: Click
Tools -> Global Options -> Git/SVN - Fork: https://github.com/evanca/quick-portfolio
- Set GitHub page Settings on GitHub repo
- Create version control R project
- Edit
README.mdto reflect a portfolio landing page - Confirm at
.github.io, example mrecos.github.io - Edit
_config.ymlwith your name and details - Add project HTML documents to folder
- Edit
index.mdto point to your project HTML, PDF, MD, or websites - Keep it up to date!
Step 1 - Make GitHub account
Go to https://github.com/ 
Step 2 - Install Git
A program called Git is the underlying technology that allows for Rstudio and GitHub to communicate and perform version control. Git is considered a protocol as it defines how other programs communicate version control. Before Rstudio will work with version control, you need to install Git on your computer. You can visit the Git website and also check out Using Git with RStudio for some helpful instructions. It is usually a pretty easy install and you will want to accept the default settings most likely. Note that the Git protocol is very powerful and has many more features than the simple use case here.
Step 3 - Configure Rstudio
There is a final setup step required to let Rstudio know that you have installed Git and where to look for it. In Rstudio click Tools -> Global Options -> Git/SVN. The check box for “Enable version control interface for Rstudio projects” should be checked and the box for “Git executable” should be the location in which in installed Git in the previous step.
Rstudio Git Settings
Step 4 - “Fork” the Repo
The term “fork” means to copy a GitHub code repository (aka “repo”) to your account. Your new repo and the original will be linked, but they will not update to each other unless specifically told to do so via a “pull request”. Forking the Simple Portfolio repo by user evanca will copy all of the code required for the portfolio into your GitHub account. The “fork” button is in the upper-right hand corner of the original repo.
Fork_repo
Step 5 - Setup GitHub Pages
In order for your GitHub repo to be view able as a webpage, you need to tell GitHub to set it up as a “GitHub Page”. On your fork of the repo, so to the setting (gear icon) and scroll down to the “GitHub Pages” section and set the Source to Change-the-layout.
Repo_settings1
Next change the name of the repo to what you want to follow the URL <<username>>.github.io, for example portfolio. NOTE! the <<username>> part of that is to be replaced with your actual GitHub Username. Mine is mrecos so my repo is called mrecos.github.io/portfolio. This will be the URL that you go to for your portfolio.
Repo_settings2
Step 6 - Create Version Controlled GitHub Rstudio Project
You can interact with your GitHub account in a number of ways, but we will use Rstudio as the means for editing and managing out portfolio. To setup Rstudio to do so, you need to create a New Project
new_project
Rstudio has a few different project formats, but you will pick the Version Control project to let Rstudio know you want to create a project from a GitHub repo.
version_control
There are two options for version controlled Rstudio projects, but we will chose Git.
version_control2
Cut/Paste the URL to your version of the portfolio repo into the “Repository URL”, the project name will populate as username. Finally, choose a directory to store your repo/files/code and make sure it is easy enough to navigate to; you will go there a bunch. Once you hit Create Project, Rstudio will go to that URL and copy all of the code to your hard drive; this is called cloning a repo.
git_clone
If everything went well, you will have a Git tab on your “Environments, History, etc…” tab in Rstudio (mine is lower-left, but yours may not be).
git_tab
Step 7 - Make Changes and Commit!
The two main git operations we will use are commit and push. Commit means to save changes in files to a special git database on your local hard drive. The the push command communicates these changes with GitHub, lets you know if all the files sync up, and if all is clear it uploads the changed files. This is how the version control aspect of GitHub work.
Open the README.md from your repo/project in Rstudio and start making some changes. This file is written in markdown and will be the landing page for your portfolio repo from the GitHub point of view (the back door if you will). Use the same types of markdown syntax as you do with Rmarkdown, but note that R code blocks will not be evaluated in a basic *.md document.
README edit
Once you make some edits, go to the Git tab in Rstudio and you will see the names of the files that have changed. Click on the Commit button to stage your changes to be pushed to the GitHub. The image below is the staging area where you will need to click on the check-box next to each file that you want to commit the changes from. On the upper-right is a place to write a commit message. Make use of this space to write detailed messages. Click the Commit button.
git_commit
Once committed, click the Push button to send it to the server. You will likely have to type in your GitHub username and password each time you push code. I status message will appear and hopefully everything goes well!
git_push
Step 8 - Go to your GitHub repo
If all went well in step 7, you should be able to go to your GitHub repo and see the new changes to the README after you refresh your browser. The README acts as a advertisement to your repo. Since this repo is more likely to be view from the web side through your github.io address, the README is more to let people know that this is your portfolio and they should go to the github.io address to see it. However, seeing changes here will confirm that everything is working.
README on GitHub
Step 9 - Edit _config.yml
The next step is to update some of your details for the actual portfolio page. Your name, occupation, social media links and such are stored in the _config.yml file in your repo. Open that file in Rstudio, make the changes, save and then commit your changes on the Git tab.
_config.yml
Step 10 - Add Portfolio Content
At this point, you can start collecting the links, HTML markdowns, and documents you want in your portfolio. This will differ for each person, but any knit markdowns (in HTML or PDF) that you want to use should be placed in a folder in your portfolio folder on your local hard rive. This is the folder that was created by Rstudio when you cloned your GitHub repo. You can add folders to that folder, I created a folder called project_markdown, but you can call it what you want. Whatever files you put in this folder, you will commit and push to your GitHub repo on the server.
Your portfolio can also link to other content you have on the web or other repos on GitHub. The next step is where you will make the edits to your portfolio webpage.
Step 11 - Edit index.md to Build Your Portfolio
The final step is to edit the index.md file to layout the content in your portfolio. The index.md file is a simple markdown file that will be converted to a static html file by the GitHub server and view-able at your github.io address. This file is (very purposefully) simple and only require a bit of tweaking to link to your content. Additionally, there is a sample_page.md file that can serve as a template for a project specific page in your portfolio. Out on the web, there are a number of more interesting and advanced templates in either markdown or HTML. Feel free to experiment
For this exercise, you can simply edit the links under “Category 1” to point to either the files you have added to your folder (see example in the image below for Philadelphia Tax Project), link out to content on the web, or build individual project pages using the sample_page.md template. Using the basics of markdown, you can build out this page however you like!
index.html
After a few changes, make sure you commit and push your changes to the server. Then go to your <
github.io Portfolio
Step 11 - Keep it up to date!
Continue to iterate the above steps and add to your portfolio. Experiment with the markdown, content presentation, and themes to make it uniquely you.